reserveSubscriptionCharge

HTTP method: POST

Use the reserveSubscriptionCharge to preauthorise, or reserve a single occurrence of an agreement payment, for example a monthly subscription.

Test URL https://testgateway.altapaysecure.com/merchant/API/<method>
Production URL https://<YourShopName>.altapaysecure.com/merchant/API/<method>

To reserve several payments, you call the method multiple times.

In addition to the payment amount, you can add a separate surcharge amount.

The old method name, preauthRecurring is deprecated, and should not be used anymore.

Parameter Description Type Mandatory
agreement[id] / transaction_id The id of the setup agreement transaction. The transaction_id is deprecated but still can be used as an alias for agreement[id] for a while, but we encourage you to use agreement[id]. [0-9a-f]{1,32} X
amount The amount to capture. float  
surcharge_amount The surcharge to capture in addition to the payment amount. This is not supported by all providers. float  
transaction_info

This is a one-dimensional associative array, where you can put any value that you would like to associate with the payment.

It is required to set the transaction_info[description] parameter when using MobilePay Subscriptions. This value will be displayed in the customer mobile app as details about the unscheduled charge.

 Array
Maximum 50 entries of maximum 255 characters each

Yes, in case of MobilePay Subscriptions.
agreement[unscheduled_type]

This is the type of the unscheduled agreement. In case you charge an agreement that has agreement[type]=unscheduled, the agreement[unscheduled_type] parameter is mandatory.

Possible values:

  • incremental (Notes: No cardholder authentication required)
  • resubmission (Notes: No cardholder authentication required)
  • delayedCharges (Notes: No cardholder authentication required)
  • reauthorisation (Notes: No cardholder authentication required)
  • noShow (Notes: No cardholder authentication required)
  • charge (Notes: SCA takes place)
 String
   Yes, when charge an unscheduled agreement.
agreement[retry_days]

The number of days when the provider will retry the charge.

Used in charge wallet agreements requests.

 integer
   No. Default value: 2
orderLines

The individual line items of the order. This is mandatory for some providers, and recommended for a good customer experience.

See details here

 Array No
dynamic_descriptor The description that appears on users bank statement. This is normally set on the terminal configuration but is provided here as an API parameter to overwrite the configuration when needed on a per-payment granularity.

It has a unique format of {string(25)}*{string(13)}
The first part of the string should represent the business name separated with a * and then an identifier.
This identifier can be used as template. Valid template inputs are %orderId, %paymentId, %currency.numeric, %currency.alpha, %customer.ip, %customer.email, %customer.phone, %customer.username.

An example payment with orderId=123 by a business Computers&Company could be CompCo*%orderId which would produce CompCo*123 on the customer's bank statement.

Caution: The underlying value of the templated identifier is what counts towards the maximum length of 13 and if it exceeds legal values it will depend on the terminal's dynamic descriptor policy whether it will be passed to the acquirer or not. 		String (39)
No, but only available for processing with Shift4 Acquirer
  • When the callback is not specified, then the callbacks from the original payment request will be used

Parameter

Description

Type

 Mandatory?
config[callback_ok] This url is called when a payment succeeds, and corresponds to the Callback url (Ok) setting in Terminal settings. For more information, see Settings for the Payment OK page (callback_ok). String (Url) No
config[callback_fail] This url is called when a payment fails, and corresponds to the Callback url (Fail) setting in Terminal settings. For more information, see Settings for the fail page (callback_fail).

As Swish only allows one open payment at a time, the callback_fail form for Swish could offer some explanation, such as "The customer may have an open payment" or "The customer should check their Swish app for open payments".

 String (Url) No

The table shows the most pertinent response values for the method. For a complete list of API response parameters, see API Response structure (XML).

Parameter Description Type
Result Success, Fail or Redirect. string

Request

  curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/reserveSubscriptionCharge \
  --header 'Authorization: Basic auth' \
  --data `agreement[id]`=1 \
  --data `agreement[unscheduled_type]`=incremental \
  --data amount=50 \

XML result

<?xml version="1.0" encoding="utf-8" ?>
<APIResponse version="20170228">
	<Header>
		<Date>2020-09-29T12:34:56+02:00</Date>
		<Path>API/reserveSubscriptionCharge</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage></ErrorMessage>
	</Header>
	<Body>
		<Result>Success</Result>
		<Transactions>
			<Transaction>
				<TransactionId>1</TransactionId>
				<PaymentId>5387ebc9-f5d9-49f1-8b4d-44746369977a</PaymentId>
				<CardStatus>Valid</CardStatus>
				<CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken>
				<CreditCardMaskedPan>411111******1111</CreditCardMaskedPan>
				<ThreeDSecureResult>Not_Applicable</ThreeDSecureResult>
				<LiableForChargeback>Merchant</LiableForChargeback>
				<BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken>
				<ShopOrderId>myorderid</ShopOrderId>
				<Shop>AltaPay Shop</Shop>
				<Terminal>AltaPay Test Terminal</Terminal>
				<TransactionStatus>recurring_confirmed</TransactionStatus>
				<ReasonCode>NONE</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
				<CardHolderCurrency>978</CardHolderCurrency>
				<CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
				<ReservedAmount>0</ReservedAmount>
				<CapturedAmount>0</CapturedAmount>
				<RefundedAmount>0</RefundedAmount>
				<RecurringDefaultAmount>10.00</RecurringDefaultAmount>
				<CreatedDate>2010-09-28 12:34:56</CreatedDate>
				<UpdatedDate>2010-09-28 12:34:56</UpdatedDate>
				<PaymentNature>CreditCard</PaymentNature>
				<PaymentNatureService name="TestAcquirer">
					<SupportsRefunds>true</SupportsRefunds>
					<SupportsRelease>true</SupportsRelease>
					<SupportsMultipleCaptures>true</SupportsMultipleCaptures>
					<SupportsMultipleRefunds>false</SupportsMultipleRefunds>
				</PaymentNatureService>
				<FraudRiskScore>13.37</FraudRiskScore>
				<FraudExplanation>Fraud detection explanation</FraudExplanation>
				<PaymentInfos>
					<PaymentInfo name="Form_Created_At">2010-09-28 12:34:56</PaymentInfo>
					<PaymentInfo name="Form_Provider">AltaPay Test Form</PaymentInfo>
					<PaymentInfo name="Merchant_Provided_Info">Some info by merchant</PaymentInfo>
				</PaymentInfos>
				<CustomerInfo/>
				<ReconciliationIdentifiers/>
			</Transaction>
			<Transaction>
				<TransactionId>2</TransactionId>
				<PaymentId>ccc1479c-37f9-4962-8d2c-662d75117e9d</PaymentId>
				<CardStatus>Valid</CardStatus>
				<CreditCardToken>93f534a2f5d66d6ab3f16c8a7bb7e852656d4bb2</CreditCardToken>
				<CreditCardMaskedPan>411111******1111</CreditCardMaskedPan>
				<ThreeDSecureResult>Not_Applicable</ThreeDSecureResult>
				<LiableForChargeback>Merchant</LiableForChargeback>
				<BlacklistToken>4f244dec4907eba0f6432e53b17a60ebcf51365e</BlacklistToken>
				<ShopOrderId>myorderid</ShopOrderId>
				<Shop>AltaPay Shop</Shop>
				<Terminal>AltaPay Test Terminal</Terminal>
				<TransactionStatus>preauth</TransactionStatus>
				<ReasonCode>NONE</ReasonCode>
				<MerchantCurrency>978</MerchantCurrency>
				<MerchantCurrencyAlpha>EUR</MerchantCurrencyAlpha>
				<CardHolderCurrency>978</CardHolderCurrency>
				<CardHolderCurrencyAlpha>EUR</CardHolderCurrencyAlpha>
				<ReservedAmount>5.00</ReservedAmount>
				<CapturedAmount>0</CapturedAmount>
				<RefundedAmount>0</RefundedAmount>
				<RecurringDefaultAmount>0</RecurringDefaultAmount>
				<CreatedDate>2010-09-28 12:34:56</CreatedDate>
				<UpdatedDate>2010-09-28 12:34:56</UpdatedDate>
				<PaymentNature>CreditCard</PaymentNature>
				<PaymentNatureService name="TestAcquirer">
					<SupportsRefunds>true</SupportsRefunds>
					<SupportsRelease>true</SupportsRelease>
					<SupportsMultipleCaptures>true</SupportsMultipleCaptures>
					<SupportsMultipleRefunds>false</SupportsMultipleRefunds>
				</PaymentNatureService>
				<FraudRiskScore>13.37</FraudRiskScore>
				<FraudExplanation>Fraud detection explanation</FraudExplanation>
				<PaymentInfos>
					<PaymentInfo name="Form_Created_At">2010-09-28 12:34:56</PaymentInfo>
					<PaymentInfo name="Form_Provider">AltaPay Test Form</PaymentInfo>
					<PaymentInfo name="Merchant_Provided_Info">Some info by merchant</PaymentInfo>
				</PaymentInfos>
				<CustomerInfo/>
				<ReconciliationIdentifiers/>
			</Transaction>
		</Transactions>
	</Body>
</APIResponse>

Redirect XML response

The redirect response will be used to involve the customer in order to authenticate the transaction.

<?xml version="1.0" encoding="utf-8" ?>
<APIResponse version="20170228">
	<Header>
		<Date>2021-11-16T08:19:10+00:00</Date>
		<Path>API/reserveSubscriptionCharge</Path>
		<ErrorCode>0</ErrorCode>
		<ErrorMessage/>
	</Header>
    <Body>
        <Result>Redirect</Result>
        <RedirectResponse>
          <Url>https://testgateway.altapaysecure.com/eCommerce/API/3ds/737f04f7-2eeb-46c6-b003-a1a623cd2443/input?callback=https%3A%2F%2Ftestgateway.altapaysecure.com%2FeCommerce%2FAPI%2FValidatePaymentAuthenticationCollect3DSDataCallback%2Fdf176859-e715-4104-b101-6841ce14a042</Url>
          <Method>GET</Method>
          <Data/>
        </RedirectResponse>
    </Body>
</APIResponse>

Use the following to test credit card transactions.

Fails at reserveSubscriptionCharge Failed 13.66
  • Pattern: ????????????1366
  • Visa: 4180000000001366
  • MasterCard: 5500000000001366
Fails at reserveSubscriptionCharge Error 13.67
  • Pattern: ????????????1367
  • Visa: 4130000000001367
  • MasterCard: 5590000000001367

Use the following to test credit card transactions when set up the subscription to trigger SCA. It will trigger the SCA for both setup subscription and charge subscription.

If the M character in the credit card number is 1, the 3DSecure v2 method flow will be triggered.

Scenario Transaction status Trigger card number

The reserve subscription charge was initiated and a frictionless flow was triggered.

 TransactionStatus.ACCEPTED
  • Visa: 411100000000051M or 457100000000081M
  • MasterCard: 517000000000001M
  • Example:  4111000000000511

The reserve subscription charge was initiated and a challenge flow was triggered.

 TransactionStatus.CHALLENGE
  • Visa 411100000000112M or 457100000000062M
  • MasterCard 517000000000992M
  • Example:  4111000000001121

The reserve subscription charge was initiated and a decoupled challenge flow was triggered.

 TransactionStatus.DECOUPLED
  • Visa: 411100000000013M or 457100000000123M
  • MasterCard:  517000000000553M
  • Example:  4111000000000131

In order to trigger the Authenticated or Rejected result upon authentication, please do so by clicking one of the following buttons in the Mock ACS (testbank):

If a payment was reserved, you can

If a payment was reserved and captured, you can: